<!DOCTYPE html>
<html lang="en">
<head>
	<meta charset="UTF-8">
	<meta http-equiv="X-UA-Compatible" content="IE=edge">
    <meta name="viewport" content="width=device-width, initial-scale=1">
	<title>Common options | ElasticSearch 7.7 权威指南中文版</title>
	<meta name="keywords" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <meta name="description" content="ElasticSearch 权威指南中文版, elasticsearch 7, es7, 实时数据分析，实时数据检索" />
    <!-- Give IE8 a fighting chance -->
    <!--[if lt IE 9]>
    <script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
    <script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
    <![endif]-->
	<link rel="stylesheet" type="text/css" href="../static/styles.css" />
	<script>
	var _link = 'common-options.html';
    </script>
</head>
<body>
<div class="main-container">
    <section id="content">
        <div class="content-wrapper">
            <section id="guide" lang="zh_cn">
                <div class="container">
                    <div class="row">
                        <div class="col-xs-12 col-sm-8 col-md-8 guide-section">
                            <div style="color:gray; word-break: break-all; font-size:12px;">原英文版地址: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.7/common-options.html" rel="nofollow" target="_blank">https://www.elastic.co/guide/en/elasticsearch/reference/7.7/common-options.html</a>, 原文档版权归 www.elastic.co 所有<br/>本地英文版地址: <a href="../en/common-options.html" rel="nofollow" target="_blank">../en/common-options.html</a></div>
                        <!-- start body -->
                  <div class="page_header">
<strong>重要</strong>: 此版本不会发布额外的bug修复或文档更新。最新信息请参考 <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/index.html" rel="nofollow">当前版本文档</a>。
</div>
<div id="content">
<div class="breadcrumbs">
<span class="breadcrumb-link"><a href="index.html">Elasticsearch Guide [7.7]</a></span>
»
<span class="breadcrumb-link"><a href="rest-apis.html">REST APIs</a></span>
»
<span class="breadcrumb-link"><a href="api-conventions.html">API conventions</a></span>
»
<span class="breadcrumb-node">Common options</span>
</div>
<div class="navheader">
<span class="prev">
<a href="cron-expressions.html">« Cron expressions</a>
</span>
<span class="next">
<a href="url-access-control.html">URL-based access control »</a>
</span>
</div>
<div class="section">
<div class="titlepage"><div><div>
<h2 class="title">
<a id="common-options"></a>Common options<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h2>
</div></div></div>
<p>The following options can be applied to all of the REST APIs.</p>
<h4>
<a id="_pretty_results"></a>Pretty Results<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>When appending <code class="literal">?pretty=true</code> to any request made, the JSON returned
will be pretty formatted (use it for debugging only!). Another option is
to set <code class="literal">?format=yaml</code> which will cause the result to be returned in the
(sometimes) more readable yaml format.</p>
<h4>
<a id="_human_readable_output"></a>Human readable output<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>Statistics are returned in a format suitable for humans
(e.g. <code class="literal">"exists_time": "1h"</code> or <code class="literal">"size": "1kb"</code>) and for computers
(e.g. <code class="literal">"exists_time_in_millis": 3600000</code> or <code class="literal">"size_in_bytes": 1024</code>).
The human readable values can be turned off by adding <code class="literal">?human=false</code>
to the query string. This makes sense when the stats results are
being consumed by a monitoring tool, rather than intended for human
consumption.  The default for the <code class="literal">human</code> flag is
<code class="literal">false</code>.</p>
<h4>
<a id="date-math"></a>Date Math<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>Most parameters which accept a formatted date value — such as <code class="literal">gt</code> and <code class="literal">lt</code>
in <a class="xref" href="query-dsl-range-query.html" title="Range query"><code class="literal">range</code> queries</a>, or <code class="literal">from</code> and <code class="literal">to</code>
in <a class="xref" href="search-aggregations-bucket-daterange-aggregation.html" title="Date Range Aggregation"><code class="literal">daterange</code>
aggregations</a> — understand date maths.</p>
<p>The expression starts with an anchor date, which can either be <code class="literal">now</code>, or a
date string ending with <code class="literal">||</code>. This anchor date can optionally be followed by
one or more maths expressions:</p>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<code class="literal">+1h</code>: Add one hour
</li>
<li class="listitem">
<code class="literal">-1d</code>: Subtract one day
</li>
<li class="listitem">
<code class="literal">/d</code>: Round down to the nearest day
</li>
</ul>
</div>
<p>The supported time units differ from those supported by <a class="xref" href="common-options.html#time-units" title="Time units">time units</a> for durations.
The supported units are:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">y</code>
</p>
</td>
<td valign="top">
<p>
Years
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">M</code>
</p>
</td>
<td valign="top">
<p>
Months
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">w</code>
</p>
</td>
<td valign="top">
<p>
Weeks
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">d</code>
</p>
</td>
<td valign="top">
<p>
Days
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">h</code>
</p>
</td>
<td valign="top">
<p>
Hours
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">H</code>
</p>
</td>
<td valign="top">
<p>
Hours
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">m</code>
</p>
</td>
<td valign="top">
<p>
Minutes
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">s</code>
</p>
</td>
<td valign="top">
<p>
Seconds
</p>
</td>
</tr>
</tbody>
</table>
</div>
<p>Assuming <code class="literal">now</code> is <code class="literal">2001-01-01 12:00:00</code>, some examples are:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">now+1h</code>
</p>
</td>
<td valign="top">
<p>
<code class="literal">now</code> in milliseconds plus one hour. Resolves to: <code class="literal">2001-01-01 13:00:00</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">now-1h</code>
</p>
</td>
<td valign="top">
<p>
<code class="literal">now</code> in milliseconds minus one hour. Resolves to: <code class="literal">2001-01-01 11:00:00</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">now-1h/d</code>
</p>
</td>
<td valign="top">
<p>
<code class="literal">now</code> in milliseconds minus one hour, rounded down to UTC 00:00. Resolves to: <code class="literal">2001-01-01 00:00:00</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">2001.02.01\|\|+1M/d</code>
</p>
</td>
<td valign="top">
<p>
<code class="literal">2001-02-01</code> in milliseconds plus one month. Resolves to: <code class="literal">2001-03-01 00:00:00</code>
</p>
</td>
</tr>
</tbody>
</table>
</div>
<h4>
<a id="common-options-response-filtering"></a>Response Filtering<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>All REST APIs accept a <code class="literal">filter_path</code> parameter that can be used to reduce
the response returned by Elasticsearch. This parameter takes a comma
separated list of filters expressed with the dot notation:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_search?q=elasticsearch&amp;filter_path=took,hits.hits._id,hits.hits._score</pre>
</div>
<div class="console_widget" data-snippet="snippets/1333.console"></div>
<p>Responds:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "took" : 3,
  "hits" : {
    "hits" : [
      {
        "_id" : "0",
        "_score" : 1.6375021
      }
    ]
  }
}</pre>
</div>
<p>It also supports the <code class="literal">*</code> wildcard character to match any field or part
of a field’s name:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_cluster/state?filter_path=metadata.indices.*.stat*</pre>
</div>
<div class="console_widget" data-snippet="snippets/1334.console"></div>
<p>Responds:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "metadata" : {
    "indices" : {
      "twitter": {"state": "open"}
    }
  }
}</pre>
</div>
<p>And the <code class="literal">**</code> wildcard can be used to include fields without knowing the
exact path of the field. For example, we can return the Lucene version
of every segment with this request:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_cluster/state?filter_path=routing_table.indices.**.state</pre>
</div>
<div class="console_widget" data-snippet="snippets/1335.console"></div>
<p>Responds:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "routing_table": {
    "indices": {
      "twitter": {
        "shards": {
          "0": [{"state": "STARTED"}, {"state": "UNASSIGNED"}]
        }
      }
    }
  }
}</pre>
</div>
<p>It is also possible to exclude one or more fields by prefixing the filter with the char <code class="literal">-</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_count?filter_path=-_shards</pre>
</div>
<div class="console_widget" data-snippet="snippets/1336.console"></div>
<p>Responds:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "count" : 5
}</pre>
</div>
<p>And for more control, both inclusive and exclusive filters can be combined in the same expression. In
this case, the exclusive filters will be applied first and the result will be filtered again using the
inclusive filters:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET /_cluster/state?filter_path=metadata.indices.*.state,-metadata.indices.logstash-*</pre>
</div>
<div class="console_widget" data-snippet="snippets/1337.console"></div>
<p>Responds:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "metadata" : {
    "indices" : {
      "index-1" : {"state" : "open"},
      "index-2" : {"state" : "open"},
      "index-3" : {"state" : "open"}
    }
  }
}</pre>
</div>
<p>Note that Elasticsearch sometimes returns directly the raw value of a field,
like the <code class="literal">_source</code> field. If you want to filter <code class="literal">_source</code> fields, you should
consider combining the already existing <code class="literal">_source</code> parameter (see
<a class="xref" href="docs-get.html#get-source-filtering" title="Source filtering">Get API</a> for more details) with the <code class="literal">filter_path</code>
parameter like this:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /library/book?refresh
{"title": "Book #1", "rating": 200.1}
POST /library/book?refresh
{"title": "Book #2", "rating": 1.7}
POST /library/book?refresh
{"title": "Book #3", "rating": 0.1}
GET /_search?filter_path=hits.hits._source&amp;_source=title&amp;sort=rating:desc</pre>
</div>
<div class="console_widget" data-snippet="snippets/1338.console"></div>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "hits" : {
    "hits" : [ {
      "_source":{"title":"Book #1"}
    }, {
      "_source":{"title":"Book #2"}
    }, {
      "_source":{"title":"Book #3"}
    } ]
  }
}</pre>
</div>
<h4>
<a id="_flat_settings"></a>Flat Settings<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>The <code class="literal">flat_settings</code> flag affects rendering of the lists of settings. When the
<code class="literal">flat_settings</code> flag is <code class="literal">true</code>, settings are returned in a flat format:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_settings?flat_settings=true</pre>
</div>
<div class="console_widget" data-snippet="snippets/1339.console"></div>
<p>Returns:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "twitter" : {
    "settings": {
      "index.number_of_replicas": "1",
      "index.number_of_shards": "1",
      "index.creation_date": "1474389951325",
      "index.uuid": "n6gzFZTgS664GUfx0Xrpjw",
      "index.version.created": ...,
      "index.provided_name" : "twitter"
    }
  }
}</pre>
</div>
<p>When the <code class="literal">flat_settings</code> flag is <code class="literal">false</code>, settings are returned in a more
human readable structured format:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">GET twitter/_settings?flat_settings=false</pre>
</div>
<div class="console_widget" data-snippet="snippets/1340.console"></div>
<p>Returns:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "twitter" : {
    "settings" : {
      "index" : {
        "number_of_replicas": "1",
        "number_of_shards": "1",
        "creation_date": "1474389951325",
        "uuid": "n6gzFZTgS664GUfx0Xrpjw",
        "version": {
          "created": ...
        },
        "provided_name" : "twitter"
      }
    }
  }
}</pre>
</div>
<p>By default <code class="literal">flat_settings</code> is set to <code class="literal">false</code>.</p>
<h4>
<a id="_parameters_14"></a>Parameters<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>Rest parameters (when using HTTP, map to HTTP URL parameters) follow the
convention of using underscore casing.</p>
<h4>
<a id="_boolean_values"></a>Boolean Values<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>All REST API parameters (both request parameters and JSON body) support
providing boolean "false" as the value <code class="literal">false</code> and boolean "true" as the
value <code class="literal">true</code>. All other values will raise an error.</p>
<h4>
<a id="_number_values"></a>Number Values<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>All REST APIs support providing numbered parameters as <code class="literal">string</code> on top
of supporting the native JSON number types.</p>
<h4>
<a id="time-units"></a>Time units<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>Whenever durations need to be specified, e.g. for a <code class="literal">timeout</code> parameter, the duration must specify
the unit, like <code class="literal">2d</code> for 2 days.  The supported units are:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">d</code>
</p>
</td>
<td valign="top">
<p>
Days
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">h</code>
</p>
</td>
<td valign="top">
<p>
Hours
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">m</code>
</p>
</td>
<td valign="top">
<p>
Minutes
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">s</code>
</p>
</td>
<td valign="top">
<p>
Seconds
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">ms</code>
</p>
</td>
<td valign="top">
<p>
Milliseconds
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">micros</code>
</p>
</td>
<td valign="top">
<p>
Microseconds
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">nanos</code>
</p>
</td>
<td valign="top">
<p>
Nanoseconds
</p>
</td>
</tr>
</tbody>
</table>
</div>
<h4>
<a id="byte-units"></a>Byte size units<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>Whenever the byte size of data needs to be specified, e.g. when setting a buffer size
parameter, the value must specify the unit, like <code class="literal">10kb</code> for 10 kilobytes. Note that
these units use powers of 1024, so <code class="literal">1kb</code> means 1024 bytes. The supported units are:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">b</code>
</p>
</td>
<td valign="top">
<p>
Bytes
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">kb</code>
</p>
</td>
<td valign="top">
<p>
Kilobytes
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">mb</code>
</p>
</td>
<td valign="top">
<p>
Megabytes
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">gb</code>
</p>
</td>
<td valign="top">
<p>
Gigabytes
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">tb</code>
</p>
</td>
<td valign="top">
<p>
Terabytes
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">pb</code>
</p>
</td>
<td valign="top">
<p>
Petabytes
</p>
</td>
</tr>
</tbody>
</table>
</div>
<h4>
<a id="size-units"></a>Unit-less quantities<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>Unit-less quantities means that they don’t have a "unit" like "bytes" or "Hertz" or "meter" or "long tonne".</p>
<p>If one of these quantities is large we’ll print it out like 10m for 10,000,000 or 7k for 7,000. We’ll still print 87
when we mean 87 though. These are the supported multipliers:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">k</code>
</p>
</td>
<td valign="top">
<p>
Kilo
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">m</code>
</p>
</td>
<td valign="top">
<p>
Mega
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">g</code>
</p>
</td>
<td valign="top">
<p>
Giga
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">t</code>
</p>
</td>
<td valign="top">
<p>
Tera
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">p</code>
</p>
</td>
<td valign="top">
<p>
Peta
</p>
</td>
</tr>
</tbody>
</table>
</div>
<h4>
<a id="distance-units"></a>Distance Units<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>Wherever distances need to be specified, such as the <code class="literal">distance</code> parameter in
the <a class="xref" href="query-dsl-geo-distance-query.html" title="Geo-distance query">Geo-distance</a>), the default unit is meters if none is specified.
Distances can be specified in other units, such as <code class="literal">"1km"</code> or
<code class="literal">"2mi"</code> (2 miles).</p>
<p>The full list of units is listed below:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
Mile
</p>
</td>
<td valign="top">
<p>
<code class="literal">mi</code> or <code class="literal">miles</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
Yard
</p>
</td>
<td valign="top">
<p>
<code class="literal">yd</code> or <code class="literal">yards</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
Feet
</p>
</td>
<td valign="top">
<p>
<code class="literal">ft</code> or <code class="literal">feet</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
Inch
</p>
</td>
<td valign="top">
<p>
<code class="literal">in</code> or <code class="literal">inch</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
Kilometer
</p>
</td>
<td valign="top">
<p>
<code class="literal">km</code> or <code class="literal">kilometers</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
Meter
</p>
</td>
<td valign="top">
<p>
<code class="literal">m</code> or <code class="literal">meters</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
Centimeter
</p>
</td>
<td valign="top">
<p>
<code class="literal">cm</code> or <code class="literal">centimeters</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
Millimeter
</p>
</td>
<td valign="top">
<p>
<code class="literal">mm</code> or <code class="literal">millimeters</code>
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
Nautical mile
</p>
</td>
<td valign="top">
<p>
<code class="literal">NM</code>, <code class="literal">nmi</code>, or <code class="literal">nauticalmiles</code>
</p>
</td>
</tr>
</tbody>
</table>
</div>
<h4>
<a id="fuzziness"></a>Fuzziness<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>Some queries and APIs support parameters to allow inexact <em>fuzzy</em> matching,
using the <code class="literal">fuzziness</code> parameter.</p>
<p>When querying <code class="literal">text</code> or <code class="literal">keyword</code> fields, <code class="literal">fuzziness</code> is interpreted as a
<a href="http://en.wikipedia.org/wiki/Levenshtein_distance" class="ulink" target="_top">Levenshtein Edit Distance</a> — the number of one character changes that need to be made to one string to
make it the same as another string.</p>
<p>The <code class="literal">fuzziness</code> parameter can be specified as:</p>
<div class="informaltable">
<table border="0" cellpadding="4px">
<colgroup>
<col>
<col>
</colgroup>
<tbody valign="top">
<tr>
<td valign="top">
<p>
<code class="literal">0</code>, <code class="literal">1</code>, <code class="literal">2</code>
</p>
</td>
<td valign="top">
<p>
The maximum allowed Levenshtein Edit Distance (or number of edits)
</p>
</td>
</tr>
<tr>
<td valign="top">
<p>
<code class="literal">AUTO</code>
</p>
</td>
<td valign="top">
<p>
</p>
<p>Generates an edit distance based on the length of the term.
Low and high distance arguments may be optionally provided <code class="literal">AUTO:[low],[high]</code>. If not specified,
the default values are 3 and 6, equivalent to <code class="literal">AUTO:3,6</code> that make for lengths:</p>
<div class="variablelist">
<dl class="variablelist">
<dt>
<span class="term">
<code class="literal">0..2</code>
</span>
</dt>
<dd>
Must match exactly
</dd>
<dt>
<span class="term">
<code class="literal">3..5</code>
</span>
</dt>
<dd>
One edit allowed
</dd>
<dt>
<span class="term">
<code class="literal">&gt;5</code>
</span>
</dt>
<dd>
Two edits allowed
</dd>
</dl>
</div>
<p><code class="literal">AUTO</code> should generally be the preferred value for <code class="literal">fuzziness</code>.</p>

</td>
</tr>
</tbody>
</table>
</div>
<h4>
<a id="common-options-error-options"></a>Enabling stack traces<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>By default when a request returns an error Elasticsearch doesn’t include the
stack trace of the error. You can enable that behavior by setting the
<code class="literal">error_trace</code> url parameter to <code class="literal">true</code>. For example, by default when you send an
invalid <code class="literal">size</code> parameter to the <code class="literal">_search</code> API:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_search?size=surprise_me</pre>
</div>
<div class="console_widget" data-snippet="snippets/1341.console"></div>
<p>The response looks like:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "error" : {
    "root_cause" : [
      {
        "type" : "illegal_argument_exception",
        "reason" : "Failed to parse int parameter [size] with value [surprise_me]"
      }
    ],
    "type" : "illegal_argument_exception",
    "reason" : "Failed to parse int parameter [size] with value [surprise_me]",
    "caused_by" : {
      "type" : "number_format_exception",
      "reason" : "For input string: \"surprise_me\""
    }
  },
  "status" : 400
}</pre>
</div>
<p>But if you set <code class="literal">error_trace=true</code>:</p>
<div class="pre_wrapper lang-console">
<pre class="programlisting prettyprint lang-console">POST /twitter/_search?size=surprise_me&amp;error_trace=true</pre>
</div>
<div class="console_widget" data-snippet="snippets/1342.console"></div>
<p>The response looks like:</p>
<div class="pre_wrapper lang-console-result">
<pre class="programlisting prettyprint lang-console-result">{
  "error": {
    "root_cause": [
      {
        "type": "illegal_argument_exception",
        "reason": "Failed to parse int parameter [size] with value [surprise_me]",
        "stack_trace": "Failed to parse int parameter [size] with value [surprise_me]]; nested: IllegalArgumentException..."
      }
    ],
    "type": "illegal_argument_exception",
    "reason": "Failed to parse int parameter [size] with value [surprise_me]",
    "stack_trace": "java.lang.IllegalArgumentException: Failed to parse int parameter [size] with value [surprise_me]\n    at org.elasticsearch.rest.RestRequest.paramAsInt(RestRequest.java:175)...",
    "caused_by": {
      "type": "number_format_exception",
      "reason": "For input string: \"surprise_me\"",
      "stack_trace": "java.lang.NumberFormatException: For input string: \"surprise_me\"\n    at java.lang.NumberFormatException.forInputString(NumberFormatException.java:65)..."
    }
  },
  "status": 400
}</pre>
</div>
<h4>
<a id="_request_body_in_query_string"></a>Request body in query string<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>For libraries that don’t accept a request body for non-POST requests,
you can pass the request body as the <code class="literal">source</code> query string parameter
instead. When using this method, the <code class="literal">source_content_type</code> parameter
should also be passed with a media type value that indicates the format
of the source, such as <code class="literal">application/json</code>.</p>
<h4>
<a id="_content_type_requirements"></a>Content-Type Requirements<a class="edit_me edit_me_private" rel="nofollow" title="Editing on GitHub is available to Elastic" href="https://github.com/elastic/elasticsearch/edit/7.7/docs/reference/api-conventions.asciidoc">edit</a>
</h4>
<p>The type of the content sent in a request body must be specified using
the <code class="literal">Content-Type</code> header. The value of this header must map to one of
the supported formats that the API supports. Most APIs support JSON,
YAML, CBOR, and SMILE. The bulk and multi-search APIs support NDJSON,
JSON, and SMILE; other types will result in an error response.</p>
<p>Additionally, when using the <code class="literal">source</code> query string parameter, the
content type must be specified using the <code class="literal">source_content_type</code> query
string parameter.</p>
</div>
<div class="navfooter">
<span class="prev">
<a href="cron-expressions.html">« Cron expressions</a>
</span>
<span class="next">
<a href="url-access-control.html">URL-based access control »</a>
</span>
</div>
</div>

                  <!-- end body -->
                        </div>
                        <div class="col-xs-12 col-sm-4 col-md-4" id="right_col">
                        
                        </div>
                    </div>
                </div>
            </section>
        </div>
    </section>
</div>
<script src="../static/cn.js"></script>
</body>
</html>